---
type: integration
title: '@astrojs/vue'
description: 了解如何使用 @astrojs/vue 框架来拓展 Astro 项目中的组件支持
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/vue/'
category: renderer
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

此 **[Astro 集成][astro-integration]** 为你的 [Vue 3](https://vuejs.org/) 组件启用服务器端渲染和客户端水合。

## 安装

Astro 包含了一个 `astro add` 命令，用于自动设置官方集成。如果你愿意，可以改为[手动安装集成](#手动安装)。

安装 `@astrojs/vue`，需要在你的项目工程中依次运行以下命令：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add vue
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add vue
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add vue
  ```
  </Fragment>
</PackageManagerTabs>

如果你有任何问题，[欢迎随时在 GitHub 上开个 issue 来向我们报告](https://github.com/withastro/astro/issues) 然后尝试执行以下的手动安装步骤。

### 手动安装

首先，安装 `@astrojs/vue` 包:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/vue
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/vue
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/vue
  ```
  </Fragment>
</PackageManagerTabs>


大多数包管理器也会安装相关的对等依赖项。如果在启动 Astro 时看到 "Cannot find package 'vue'" (或类似的)警告，则需要安装 Vue：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install vue
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add vue
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add vue
  ```
  </Fragment>
</PackageManagerTabs>

然后，使用 `integrations` 属性将集成应用到你的 `astro.config.*` 文件中：

```js ins={2} ins="vue()" title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
export default defineConfig({
  // ...
  integrations: [vue()],
});
```

## 入门

要在 Astro 使用你的 Vue 组件，你可以移步我们的 [UI 框架文档][astro-ui-frameworks]。你将会了解到：

* 📦 如何加载框架组件
* 💧 客户端合成注水选项
* 🤝 将框架混合和嵌套在一起的时机

## 疑难解答

如需帮助，请查看我们在 [Discord](https://astro.build/chat) 上的  `#support` 频道。我们友好的支持小队成员随时为你提供帮助！

你也可以查看我们的 [Astro 集成文档][astro-integration] 以获取集成的更多信息。

## 贡献

该 Astro 包是由核心团队维护的，欢迎提交 issue 和 PR！

[astro-integration]: /zh-cn/guides/integrations-guide/

[astro-ui-frameworks]: /zh-cn/guides/framework-components/#使用框架组件

## 选项

此集成由 `@vitejs/plugin-vue` 提供支持。要定制 Vue 编译器，你可以为集成提供选项。查看 `@vitejs/plugin-vue` [文档](https://www.npmjs.com/package/@vitejs/plugin-vue) 获取更多详细内容。

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';

export default defineConfig({
  // ...
  integrations: [
    vue({
      template: {
        compilerOptions: {
          // 将任意以 ion- 开头的标签当做自定义元素
          isCustomElement: (tag) => tag.startsWith('ion-'),
        },
      },
      // ...
    }),
  ],
});
```

### appEntrypoint

你可以拓展 Vue `app` 实例并将 `appEntrypoint` 选项设置为一个相对根目录的导入标识符 (例如： `appEntrypoint: "/src/pages/_app"`)。

此文件的默认导出应该是一个接收 Vue `App` 实例的函数，允许使用 [自定义 Vue 插件](https://vuejs.org/guide/reusability/plugins.html)，`app.use` 和其他高级使用情形的定制。

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';

export default defineConfig({
  // ...
  integrations: [vue({ appEntrypoint: '/src/pages/_app' })],
});
```

```ts title="src/pages/_app.ts"
import type { App } from 'vue';
import i18nPlugin from 'my-vue-i18n-plugin';

export default (app: App) => {
  app.use(i18nPlugin);
};
```

### jsx

你可以通过设置 `jsx: true` 来使用 Vue JSX。

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';

export default defineConfig({
  // ...
  integrations: [vue({ jsx: true })],
});
```

这将会为 Vue 和 Vue JSX 组件 开启渲染，要定制 Vue JSX 编译器的话，可以把传递的选项由布尔值改为对象，查阅 `@vitejs/plugin-vue-jsx` [文档](https://www.npmjs.com/package/@vitejs/plugin-vue-jsx) 获取更多细节内容。

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';

export default defineConfig({
  // ...
  integrations: [
    vue({
      jsx: {
        // 将任意以 ion- 开头的标签当做自定义元素
        isCustomElement: (tag) => tag.startsWith('ion-'),
      },
    }),
  ],
});
```
